<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="embroot.css">
<TITLE>
Coding External Predicates
</TITLE>
</HEAD>
<BODY >
<A HREF="embroot012.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot014.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc30">4.1</A>&nbsp;&nbsp;Coding External Predicates</H2>
External Predicates are C/C++ functions that can be called like predicates
from ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>.
Two following extra interface functions are provided for this purpose:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>EC_word EC_arg(int i)</B><DD CLASS="dd-description">
	returns the i'th argument of the predicate call.<BR>
<BR>
<DT CLASS="dt-description"><B>pword ec_arg(int i)</B><DD CLASS="dd-description"><BR>
	same for C.<BR>
<BR>
<DT CLASS="dt-description"><B>int unify(EC_word, EC_word)</B><DD CLASS="dd-description"><BR>
	unify two pwords. The return code indicates success or
	failure. Note however, that if attributed variables are
	involved, their handlers have not been invoked yet (this
	happens after the external predicate returns).<BR>
<BR>
<DT CLASS="dt-description"><B>int EC_word::unify(EC_word)</B><DD CLASS="dd-description"><BR>
	same as method.<BR>
<BR>
<DT CLASS="dt-description"><B>int ec_unify(pword, pword)</B><DD CLASS="dd-description"><BR>
	same for C.
</DL>
Apart from that, all functions for constructing, testing and decomposing
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> data can be used in writing the external predicate
(see chapter <A HREF="embroot007.html#chapmixed">3</A>).
Here are two examples working with lists, the first one constructing
a list in C:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
#include "eclipse.h"
int
p_string_to_list()         /* string_to_list(+String, -List) */
{
    pword  list;
    char *s;
    long len;
    int res;

    res = ec_get_string_length(ec_arg(1), &amp;s, &amp;len);
    if (res != PSUCCEED) return res;

    list = ec_nil();    /* build the list backwards */
    while (len--)
        list = ec_list(ec_long(s[len]), list);

    return ec_unify(ec_arg(2), list);
}
</PRE></BLOCKQUOTE>
The next example uses an input list of integers and sums up the numbers.
It is written in C++:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
#include "eclipseclass.h"
extern "C" int
p_sumlist()
{
    int res;
    long x, sum = 0;
    EC_word list(EC_arg(1));
    EC_word car,cdr;

    for ( ; list.is_list(car,cdr) == EC_succeed; list = cdr)
    {
        res = car.is_long(&amp;x);
        if (res != EC_succeed) return res;
        sum += x;
    }
    res = list.is_nil();
    if (res != EC_succeed) return res;
    return unify(EC_arg(2), EC_word(sum));
}
</PRE></BLOCKQUOTE>
The source code of these examples can be found in directory
doc/examples within the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> installation.<BR>
<BR>
<HR>
<A HREF="embroot012.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot014.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
